/*
Copyright 2013 Lin, Chung-Ming (aka Alva Lin. E-mail: alva0930@gmail.com)

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
*/

/**
 * An implementation of this interface specifies how to evaluate the cost and the partial derivatives for a given set of parameters.
 * <P>
 * <DL>
 * <DT><B>Sample Code:</B></DT>
 * <DD>CostGradient cg = &ltan implementation of CostGradient&gt;</DD>
 * <DD>double[] params = &lta set of parameters&gt;</DD>
 * <DD>cg.evaluate(params);</DD>
 * <DD>double cost = cg.getCost();</DD>
 * <DD>double[] derivatives = cg.getGradient();</DD>
 * </DL>
 *
 * @author	Lin, Chung-Ming (aka Alva Lin. E-mail: alva0930@gmail.com)
 */
public interface CostGradient
{
/* ------------------------
   Public Methods
 * ------------------------ */

	/**
	 * Calculate the cost and the partial derivatives for a given set of parameters.
	 *
	 * @param	parameter	a set of parameters
	 */
	public void evaluate(double[] parameter);

	/**
	 * Get the cost of the set of parameters in the last invocation of evaluate(...).
	 *
	 * @return	the cost of the set of parameters in the last invocation of evaluate(...), or unexpected result if evaluate(...) has never been invoked
	 */
	public double getCost();

	/**
	 * Get the derivatives of the set of parameters in the last invocation of evaluate(...).
	 *
	 * @return	the derivatives of the set of parameters in the last invocation of evaluate(...), or unexpected result if evaluate(...) has never been invoked
	 */
	public double[] getGradient();
}